Zum Hauptinhalt springen

E-Mail-Anhänge korrekt verarbeiten

Was du nach diesem Kapitel kannst: Du verstehst, wie 42°OS E-Mails abruft und warum Anhänge eine besondere Herausforderung darstellen. Du kennst das Standardmuster zur Vereinzelung, Verarbeitung und Zusammenführung von Anhängen — und du weißt, welche Fallstricke dich erwarten und wie du sie vermeidest.

1. Wie kommen E-Mails in die Plattform?​

42°OS kann E-Mails aus zwei Quellen abrufen:

  • IMAP-Postfächer werden über den Incoming Mail Agent abgefragt. Das funktioniert mit den meisten Standard-E-Mail-Diensten (z. B. eigene Mailserver, Gmail, GMX, etc.).
  • Microsoft 365 wird über den Microsoft Graph Email Agent angebunden, der die MS Graph API nutzt. Diese Variante ist für Unternehmensumgebungen relevant, die auf M365 setzen.

In beiden Fällen liefert der jeweilige Agent eine strukturierte JSON-Nachricht pro E-Mail. Alle Anhänge dieser E-Mail werden dabei einheitlich unter dem Schlüssel attachments als Array aufgelistet — unabhängig davon, welche Quelle genutzt wurde.

{
  "subject": "Rechnung März 2026",
  "from": "lieferant@beispiel.de",
  "body": "...",
  "attachments": [
    { "filename": "rechnung_2026_03.pdf", "content_type": "application/pdf", "data": "..." },
    { "filename": "logo.png", "content_type": "image/png", "data": "..." }
  ]
}

2. Warum sind Anhänge eine Herausforderung?​

Auf den ersten Blick klingt die Verarbeitung von Anhängen simpel. In der Praxis stößt man schnell auf drei Probleme, die man von Anfang an einplanen muss.

2.1 Unbekannte Anzahl​

Man weiß beim Aufbau eines Workflows nie, wie viele Anhänge eine eingehende E-Mail haben wird:

  • Manche E-Mails haben gar keinen Anhang.
  • Manche haben genau einen.
  • Manche haben mehrere — zum Beispiel eine Rechnung plus ein Lieferschein plus ein Logo.

Das attachments-Array kann also leer sein, einen Eintrag haben oder beliebig viele. Ein Workflow, der das nicht berücksichtigt, wird in realen Szenarien regelmäßig fehlschlagen.

2.2 Unbekannte Dateitypen​

In vielen Automatisierungen möchte man einen ganz bestimmten Dateityp verarbeiten — zum Beispiel eine PDF-Rechnung. Das Problem: In derselben E-Mail können Dateien verschiedener Typen als Anhang auftauchen. Ein Word-Dokument, ein PDF und ein Bild können gleichzeitig im attachments-Array liegen. Der Workflow muss also in der Lage sein, relevante Dateitypen gezielt herauszufiltern und irrelevante zu ignorieren oder separat zu behandeln.

2.3 Inline-Bilder werden als Anhänge interpretiert​

Ein häufig übersehenes Problem: Viele E-Mail-Clients betten Bilder direkt in den E-Mail-Body ein — zum Beispiel ein Firmenlogo in der Signatur oder ein Banner im Newsletter. Technisch gesehen werden diese Bilder aber als Anhänge übertragen und landen deshalb ebenfalls im attachments-Array. Ohne entsprechende Filterlogik würde der Workflow diese Bilder als reguläre Anhänge verarbeiten — was in den meisten Fällen nicht gewünscht ist.

💡 Erkennungsmerkmal für Inline-Bilder: Sie haben meist einen content_type vom Typ image/* (z. B. image/png, image/jpeg) und häufig ein content_id-Attribut (CID), das auf die Einbettung im HTML-Body hinweist. Diese können per Filter- oder Switch-Logik aussortiert werden.

3. Das Standardmuster: Vereinzeln, Verarbeiten, Zusammenführen​

Da die Anzahl der Anhänge variabel ist, folgt die Verarbeitung einem festen dreiteiligen Muster.

Schritt 1 — Vereinzelung mit dem JSON Split Agent​

Der JSON Split Agent nimmt die gesamte E-Mail-Nachricht entgegen und erzeugt daraus eine separate Message pro Eintrag im attachments-Array. Aus einer E-Mail mit drei Anhängen werden also drei unabhängige Nachrichten — jede enthält neben dem Anhang auch die übergeordneten E-Mail-Informationen (Betreff, Absender, etc.).

Eingehende Nachricht (1x)
  └── JSON Split Agent
        ├── Message für Anhang 1 (PDF)
        ├── Message für Anhang 2 (PNG)
        └── Message für Anhang 3 (DOCX)

Dieser Schritt ist notwendig, weil nachgelagerte Agenten — zum Beispiel ein Agent zur Dokumentenverarbeitung — immer genau einen Anhang auf einmal verarbeiten. Sie können nicht mit einem Array umgehen.

Schritt 2 — Dateitypen unterscheiden​

Nach dem Split weiß man bei jeder einzelnen Message, um welchen Dateityp es sich handelt. Hier kommt je nach Anforderung ein Switch Agent oder ein Filter Agent zum Einsatz:

  • Filter Agent: Nur Nachrichten, die eine Bedingung erfüllen (z. B. content_type == "application/pdf"), laufen weiter. Alle anderen werden verworfen.
  • Switch Agent: Verschiedene Dateitypen werden auf verschiedene Pfade geleitet — PDFs gehen in die Rechnungsverarbeitung, Word-Dokumente in einen anderen Zweig, Bilder werden ignoriert.
Message (PDF)   → Switch Agent → Pfad "PDF"   → Rechnungsverarbeitung
Message (PNG)   → Switch Agent → Pfad "Bild"  → Verwerfen / ignorieren
Message (DOCX)  → Switch Agent → Pfad "Word"  → anderer Prozess

Schritt 3 — Zusammenführen mit dem JSON Merge Agent​

Wenn am Ende des Workflows ein einzelnes, zusammengefasstes Ergebnis benötigt wird — zum Beispiel alle extrahierten Rechnungsdaten aus einer E-Mail in einer einzigen Nachricht — müssen die separat verarbeiteten Ergebnisse wieder zusammengeführt werden. Das übernimmt der JSON Merge Agent.

4. Wichtige Fallstricke​

Nach dem JSON Merge Agent: Nachrichtenstruktur prüfen​

Der JSON Merge Agent erzeugt eine zusammengeführte Nachricht, deren Struktur sich von der ursprünglichen Eingangsnachricht unterscheidet. Nachgelagerte Agenten, die eine bestimmte Struktur erwarten, können deshalb fehlschlagen. Nach jedem JSON Merge Agent lohnt es sich, die ausgehende Nachrichtenstruktur explizit zu prüfen — und bei Bedarf einen Normalisierungsschritt einzubauen.

🔗 Mehr zum Thema Normalisierung: Kapitel Zustandsnormalisierung durch SQL-Persistenz

Leere Anhang-Arrays abfangen​

Wenn eine E-Mail keine Anhänge hat, ist das attachments-Array leer. Der JSON Split Agent wird in diesem Fall keine einzige Message erzeugen — der Workflow läuft also ins Leere, ohne Fehler zu werfen. Wenn das nicht gewünscht ist (z. B. weil E-Mails ohne Anhang trotzdem protokolliert werden sollen), muss vor dem Split Agent eine Bedingungsabfrage stehen, die diesen Fall separat behandelt.

Split und Merge nur einsetzen, wenn wirklich ein Gesamtergebnis benötigt wird​

Nicht jeder Workflow muss gesplittete Nachrichten wieder zusammenführen. Wenn die Verarbeitung jedes Anhangs unabhängig voneinander abgeschlossen werden kann — zum Beispiel jeder Anhang wird direkt in ein Archiv gespeichert — ist ein Merge-Schritt unnötig und fügt nur Komplexität hinzu.

5. Zusammenfassung​

ProblemLösung
Variable Anzahl von AnhängenJSON Split Agent vereinzelt das attachments-Array
Verschiedene DateitypenSwitch Agent oder Filter Agent nach dem Split
Inline-Bilder im AnhangFilter auf content_type und/oder content_id
Ergebnis wieder zusammenführenJSON Merge Agent
Veränderte Struktur nach MergeNormalisierungsschritt einplanen
Leeres Anhang-ArrayBedingungsabfrage vor dem Split

📹 Video zu diesem Kapitel: [Platzhalter — Screencast: E-Mail-Anhänge verarbeiten — Schritt für Schritt] 📸 Screenshots: [Platzhalter — Workflow-Ansicht: Split → Filter → Merge]

Nächstes Kapitel: [[Dokumente kategorisieren]]